Planning Space Data Connector

PAGE CONTENTS

 

The Planning Space Data Connector (PDC) is an add-in for Microsoft Excel, which can be used to extract data from Planning Space into Excel, and to insert data into Planning Space. Thus, users are able to use any Excel-based functionality to seamlessly process Planning Space data.

IPS Server needs to run an additional service module to handle client requests coming from Microsoft Excel/PDC as a client application.

The PDC module is automatically-deployed during the installation of IPS Server. This topic explains the required configuration steps on the server side.

For each Planning Space tenant that needs to be accessed from PDC, you will need to create an XML manifest file. These files must be stored in a shared manifest folder (i.e. a Windows network file share) that users of PDC can access to pass the manifest file contents to Excel to configure each PDC connection. A user can run multiple (and simultaneous) PDC connections based on different tenants from their personal Excel application.

PDC end-user requirements: The minimum version of Excel to use the PDC add-in is Microsoft Office Excel 2024 (desktop application), or Microsoft 365 (Microsoft Excel for Office 365, desktop application or online). Users of the PDC will need to be informed about the location of a 'shared manifest folder' which they will use to configure their personal Excel setup; for the end-user configuration, see the topic Planning Space Data Connector in the Planning Space User Manual. Note: issues have been found with 'Excel 2024' installations not working with PDC (error message: 'This add-in will not run in your version of Office...'); if this occurs you should check that Excel is using the correct 'runtime webview' - see the previous link for details.

Automatic installation

The PDC add-in module is automatically installed and deployed by the IPS Server installer. The module is installed in the folder:

C:\Program Files\Palantir\PalantirIPS 20.4\Modules\DataConnector

PDC port configuration

The PDC will use server ports 9149 and 9249 by default. If these are otherwise in use you will need to modify the Application Ports setting in the IPS Manager Service screen.

See IPS Server Application ports.

Configure the Add-in XML manifest file

In order to access the PDC service from Excel, the user needs to have access to an Add-in manifest file, which defines the location of the PDC web application.

The first step is to edit the template manifest file.

A template manifest file is contained in the code snippet box below (click 'COPY' and then then you can paste the contents into an editor in your local machine).

These are the contents that need to be edited for each tenant:

  • MANIFESTGUID: you can generate a new unique ID using a utility such as the PowerShell command New-Guid. Example: '9be52bf6-e718-4971-b0e3-cbf30ac76959'.
  • SERVERNAME: The Planning Space service address, including a port number if the defaults 80 or 443 are not applicable. Examples: 'https://PSProd.mycompany.com', 'https://PSNonProd.mycompany.com:8443'.
  • TENANTNAME: The text name of the tenant. Example: 'DEVTEST1'
  • MANIFESTNAME: This is an identifying string which users will see when they are looking at the different manifests in Excel setup, and the same string is used for the access button in the Excel button ribbon. The suggested format is to use a short name for the Planning Space service, plus the tenant name; for example 'NonProd DEVTEST1'.

The name of the manifest file is not prescribed and it will not be visible to users in Excel. The suggested name format is to follow the MANIFESTNAME text, for example 'NonProd-DEVTEST1-manifest.xml'.

Copy 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
  xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="TaskPaneApp">
  <Id>MANIFESTGUID</Id>
  <Version>2.0.0.0</Version>
  <ProviderName>Quorum</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="MANIFESTNAME" />
  <Description
    DefaultValue="Easily report on, and update, centrally controlled planning data in Planning Space databases. Requires a login and valid licence for Planning Space." />
  <IconUrl DefaultValue="SERVERNAME/TENANTNAME/DataConnector/assets/icon-32.png" />
  <HighResolutionIconUrl DefaultValue="SERVERNAME/TENANTNAME/DataConnector/assets/icon-64.png" />
  <SupportUrl DefaultValue="https://www.quorumsoftware.com/support/" />
  <AppDomains>
    <AppDomain>https://www.quorumsoftware.com/</AppDomain>
  </AppDomains>
  <Hosts>
    <Host Name="Workbook" />
  </Hosts>
  <Requirements>
    <Sets DefaultMinVersion="1.1">
      <Set Name="SharedRuntime" MinVersion="1.1" />
    </Sets>
  </Requirements>
  <DefaultSettings>
    <SourceLocation DefaultValue="SERVERNAME/TENANTNAME/DataConnector/taskpane.html" />
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides"
    xsi:type="VersionOverridesV1_0">
    <Hosts>
      <Host xsi:type="Workbook">
        <Runtimes>
          <Runtime resid="Taskpane.Url" lifetime="long" />
        </Runtimes>
        <DesktopFormFactor>
          <FunctionFile resid="Taskpane.Url" />
          <ExtensionPoint xsi:type="PrimaryCommandSurface">
            <OfficeTab id="TabData">
              <Group id="CommandsGroup">
                <Label resid="CommandsGroup.Label" />
                <Icon>
                  <bt:Image size="16" resid="Icon.16x16" />
                  <bt:Image size="32" resid="Icon.32x32" />
                  <bt:Image size="80" resid="Icon.80x80" />
                </Icon>
                <Control xsi:type="Button" id="TaskpaneButton">
                  <Label resid="TaskpaneButton.Label" />
                  <Supertip>
                    <Title resid="TaskpaneButton.Label" />
                    <Description resid="TaskpaneButton.Tooltip" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Icon.16x16" />
                    <bt:Image size="32" resid="Icon.32x32" />
                    <bt:Image size="80" resid="Icon.80x80" />
                  </Icon>
                  <Action xsi:type="ShowTaskpane">
                    <TaskpaneId>ButtonId1</TaskpaneId>
                    <SourceLocation resid="Taskpane.Url" />
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Icon.16x16"
          DefaultValue="SERVERNAME/TENANTNAME/DataConnector/assets/icon-16.png" />
        <bt:Image id="Icon.32x32"
          DefaultValue="SERVERNAME/TENANTNAME/DataConnector/assets/icon-32.png" />
        <bt:Image id="Icon.80x80"
          DefaultValue="SERVERNAME/TENANTNAME/DataConnector/assets/icon-80.png" />
      </bt:Images>
      <bt:Urls>
        <bt:Url id="Taskpane.Url"
          DefaultValue="SERVERNAME/TENANTNAME/DataConnector/taskpane.html?tenant=TENANTNAME" />
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="CommandsGroup.Label" DefaultValue="PDC" />
        <bt:String id="TaskpaneButton.Label" DefaultValue="MANIFESTNAME" />
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="TaskpaneButton.Tooltip"
          DefaultValue="Open the Planning Space Data Connector from MANIFESTNAME" />
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</OfficeApp>

The next step is to make the manifest file available to users, as explained in the following section.

Administrator deployment of a shared manifest folder

The XML manifest file is deployed using a network share folder.

The share folder must exist in your corporate Windows network and be accessible to all Excel/PDC users. (If there are multiple manifest files in the same folder, all of them will be visible when a user is setting up thier Excel configuration.)

Copy your edited XML manifest file to the shared folder, and ensure that it will be read-accessible for all users of the Planning Space Data Connector. Each user will configure their own Excel setup with the shared folder specified as a Trusted Add-in Catalog.